home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 081-090 / amok81 / poster < prev    next >
Text File  |  1993-11-04  |  8KB  |  158 lines
  1. ===========================================================================
  2.                AMOK - Amiga Modula & Oberon Klub  Stuttgart
  3.  
  4.             "Poster": Norm bzw. Standardform für AMOK-Beiträge
  5.                Tips und Anhaltspunkte für Veröffentlichungen
  6. ===========================================================================
  7.  
  8. Einleitung
  9.  
  10. Wir  -AMOK-  sind  gerne  bereit,  auch  anderen  Modula-2-  bzw.   Oberon-
  11. Programmierern  mit  den  AMOK-Disks  einen  Weg zur Veröffentlichung Ihrer
  12. Programme  zu  bieten.   Ziel unserer PD-Reihe ist es schließlich, für eine
  13. möglichst  weite  Verbreitung von Modula & Oberon zu sorgen.  Da sich diese
  14. Programmiersprachen optimal zum Austausch von Programm-Modulen eignen, kann
  15. jeder  Programmierer  hierzu beitragen.  Je größer die Modulbibliothek ist,
  16. auf die ein Programmierer zurückgreifen kann, desto weniger muß er sich mit
  17. zeitraubenden Alltagsproblemen herumschlagen und sozusagen "das Rad zweimal
  18. erfinden".   Falls Sie also Module geschrieben haben, von denen Sie denken,
  19. daß  auch  andere  sie  gebrauchen  können, schicken Sie sie an AMOK.  Wenn
  20. irgend  möglich werden wir den Beitrag in unsere AMOK-Reihe aufnehmen.  Wir
  21. stellen  zwar  keine  Ansprüche  an die Genialität der Programme, damit Ihr
  22. Beitrag  eine  Chance  hat,  veröffentlicht zu werden, sollten Sie aber die
  23. unten  aufgeführten  Punkte  beachten.   Damit  gewährleistet ist, daß Ihre
  24. PD-Software auch wirklich brauchbar ist.
  25.  
  26.  
  27. 1) Kriterien
  28.  
  29. Wie  schon erwähnt stellen wir keine Anforderungen an das, was ein Programm
  30. besonderes  kann.   Das  was  es  kann,  soll  es aber sinnvoll und korrekt
  31. ausführen.   Ein  simples  aber  nützliches Modul hat, auch wenn es noch so
  32. banal ist, höhere Chancen, veröffentlicht zu werden, als ein Riesenprojekt,
  33. das an sich genial ist, aber ständig guru-meditiert.
  34.  
  35.  
  36. 2) AMOK Anforderungen
  37.  
  38. Die   Folgenden   Punkte   sind  verbindlich  und  von  jedem  AMOK-Beitrag
  39. einzuhalten:
  40.  
  41. * Zu  jedem  Modul(-packet)  gehört eine Dokumentation.  Ohne Dokumentation
  42.   sind  die  Module für andere unbrauchbar.  Es gibt auf den AMOK-Disketten
  43.   folgende Formen der Dokumentation:
  44.  
  45.     - Dokumentation  im Klartext in einer extra Datei mit der Endung ".dok"
  46.       (für deutsche Dokumentation) oder ".doc" (für die englische)
  47.     - stichwortartige  Kurzbeschreibung  der Prozeduren im Definitionsmodul
  48.       Diese  Form  der  Dokumentation  ist auf AMOK >= #25 bei "HeaderInfo"
  49.       genauer beschrieben.
  50.   Die Dokumentation sollte mindestens diese Informationen beinhalten:
  51.     - Bedeutung und Auswirkung der Prozedurparameter
  52.     - Funktion und Verwendungszweck der Prozeduren
  53.     - Bedeutung der Rückgabewerte der Prozeduren
  54.     - Wichtige Hinweise über exportierte Variablen, Konstanten und Typen
  55.     - Hinweise auf mögliche Fehler (soweit bekannt)
  56.     - Angaben über eventuelle Einschränkungen oder Warnungen
  57.   Wenn  möglich  sollte die Dokumentation nur aus reinem ASCII-Code und nur
  58.   mit   den   ANSI  Steuersequenzen  geschrieben  werden.   (MuchMore-  und
  59.   copy-to-prt:-verträglich)
  60.  
  61. * Der  Source-Code  sollte den Modulen immer beigefügt werden.  Schließlich
  62.   sollen  andere  Programmierer  aus  Ihrem  Programm  etwas lernen können.
  63.   Außerdem  ist  es somit möglich, eventuelle Fehler zu verbessern oder das
  64.   Programm  an  eigene Bedürfnisse anzupassen.  Als Ausnahmen sind folgende
  65.   zulässig:
  66.     - das  Programm ist wirklich ausgesprochen genial und gehört eigentlich
  67.       patentiert (es muß natürlich absolut fehlerfrei sein)
  68.     - die  Module  sind  Teile  eines  von  Ihnen  kommerziell vertriebenen
  69.       Programms, und Sie wollen nicht, daß jemand Einblick erhält
  70.     - Ihr  Programmierstil  ist  so  schlecht  und  Ihre  Methoden so haar-
  71.       sträubend,  daß  Sie  den  Source-Code  niemandem  zumuten wollen (In
  72.       diesem  Fall  sollten  Sie  sich  allerdings  Überlegen, ob Sie nicht
  73.       lieber C oder Assembler programmieren wollen)
  74.  
  75. * Definitions  und  Implementationsmodul  sollten  unseren Modulkopf (siehe
  76.   "HeaderInfo")  beinhalten.   Dieser  ist  zur  leichteren  Verwaltung der
  77.   inzwischen    mehrere    Megabyte   umfassenden   AMOK-Softwarebibliothek
  78.   notwendig.  Haltet  Euch an unsere Formatvorgaben in "HeaderInfo".
  79.  
  80. * Alle  Dateien und Unterdirectories sollen Icons haben, so daß Sie von der
  81.   Workbench  aus zugänglich sind.  Das Default-Tool von Textdateien (Source
  82.   und Dokumentation) muß auf ":c/MuchMore" eingestellt sein.
  83.  
  84.  
  85. 3) AMOK Vereinbarungen
  86.  
  87. Es wird gebeten, auch auf folgendes zu achten:
  88.  
  89. * Sollten  zum  Compilieren  eines  Moduls noch andere nicht standardmäßige
  90.   Module  benötigt  werden,  sollten  diese mitgeliefert werden.  Dabei ist
  91.   darauf  zu  achten,  daß  die  sym-Schlüssel stimmen, d.h.  alles mit der
  92.   selben  Version  der  Definitionsmodule compiliert wurde.  Existieren von
  93.   imortierten   Modulen  mehrere  Versionen,  dann  ist  anzugeben,  welche
  94.   benötigt wird. (Vermerk :Imports.)
  95.  
  96. * Im  Source-Code  und  in  der  Dokumentation  sollte man wenn möglich die
  97.   Zeilenlänge  auf  70  bis  75  Zeichen  begrenzen.   MuchMore und M2Emacs
  98.   akzeptieren  zwar  80  Zeichen, viele möchten jedoch sicherlich die Texte
  99.   ausdrucken, und da ist ein Rand ganz nützlich.
  100.  
  101. * Prozedur-,    Variablen-,   Konstanten-   und   Typenbezeichner   sollten
  102.   vorzugsweise englisch sein, ebenso die Kurzbeschreibung der Prozeduren im
  103.   Definitionsmodul (siehe AMOK#7, ProgInfo/StandardIDs).
  104.   Wenigstens  sollte  man  Englisch  und  Deutsch  nicht mischen.  Deutsche
  105.   Dokumentation sollte nicht fehlen, englische ist freiwillig.
  106.  
  107. * Kleine  Demoprogramme  dienen der leichteren Verständnis und dem besseren
  108.   Einarbeiten  in  die  Funktionen  eines Moduls.  Oft sind Testmodule oder
  109.   sonstige  Beispielanwendungen als Nebenprodukte eigener Programme sowieso
  110.   vorhanden.
  111.  
  112. * Seien  Sie  fair  gegenüber  anderen Programmierern.  Public Domain heißt
  113.   noch lange nicht "Software-Freiwild".  Wenn Sie Programmteile von anderen
  114.   übernehmen,   erwähnen   Sie   den  Autor  bitte  im  Modulkopf  oder  in
  115.   Kommentarzeilen.    Für   eine  kommerzielle  Nutzung  brauchen  Sie  die
  116.   Schriftliche  Erlaubnis  des  jewiligen Autors.  Denken Sie bitte auch an
  117.   eventuelle Shareware-Gebühren.
  118.  
  119.  
  120. 4) Zum Thema korrekte Programme
  121.  
  122. Die  folgenden Anweisungen gelten nicht speziell für AMOK-Disketten sondern
  123. sollten  von  allen  Programmierern beachtet werden.  Wenn diese Punkte für
  124. Sie noch nicht selbstverständlich sind, empfehlen wir Ihnen DRINGENDST Ihre
  125. Programme in Zukunft dementsprechend auszulegen.
  126.  
  127. * Alle  Programme  sollten  auf  korrektem Weg verlassen werden können, das
  128.   heißt,  ohne  neu  starten zu müssen, und so, daß uneingeschränkt weiter-
  129.   gearbeitet  werden  kann.   Außerdem  sollen  Sie alle Betriebsmittel und
  130.   Resourcen  an  das  System  zurückgeben  (Speicher deallozieren, Fenster,
  131.   Screens und Files schließen).
  132.  
  133. * Programme  sollten sich nicht so verhalten, als wären Sie die einzigen im
  134.   System,  sondern  auf  das Multitasking und seine Restriktionen Rücksicht
  135.   nehmen   (z.B.    gegenseitiger   Ausschluß   beim  Zugriff  auf  System-
  136.   strukturen).
  137.  
  138. * Programme  sollen  sich  gegenüber  dem Benutzer logisch und bei Fehlein-
  139.   gaben robust verhalten.
  140.  
  141. * Man sollte nie davon ausgehen, immer alle Betriebsmittel zu bekommen, die
  142.   man  anfordert.   Programme  sollen  sich  definiert verhalten, wenn z.B.
  143.   Files  nicht  geöffnet  werden  können, oder nicht mehr genügend Speicher
  144.   vorhanden ist.
  145.  
  146. * Die  Benutzerschnittstelle  soll den beim AMIGA allgemein üblichen Richt-
  147.   linien entsprechen (siehe Intuition Reference Manual Chapter 12:  Style).
  148.  
  149. * Programme   sollten  wenn  möglich  keine  spezielle  Gerätekonfiguration
  150.   vorraussetzen.
  151.  
  152. * Besonders  für die Entwicklung zukünftiger Bibliotheksmodule ist wichtig,
  153.   daß  die  Prozeduren  reentrant  sind,  falls  es  sinnvoll  ist, sie von
  154.   mehreren  Tasks  aus  gleichzeitig zu benutzen (es ist in Modula ja nicht
  155.   möglich, Module zweimal zu importieren).
  156.  
  157. --- Viel Spaß
  158.